<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
<!-- saved from url=(0074)http://check.sourceforge.net/doc/check_html/check_4.html#Advanced-Features -->
<html><!-- This manual is for Check
(version 0.9.9, 19 October 2012),
a unit testing framework for C.

Copyright C 2001-2011 Arien Malec, Chris Pickett, Fredrik
Hugosson, and Robert Lemmen.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License,
Version 1.2 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover texts, and no
Back-Cover Texts.  A copy of the license is included in the section
entitled "GNU Free Documentation License."

 --><!-- Created on November 12, 2012 by texi2html 1.82
texi2html was written by: 
            Lionel Cons <Lionel.Cons@cern.ch> (original author)
            Karl Berry  <karl@freefriends.org>
            Olaf Bachmann <obachman@mathematik.uni-kl.de>
            and many others.
Maintained by: Many creative people.
Send bugs and suggestions to <texi2html-bug@nongnu.org>
--><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Check 0.9.9: 4. Advanced Features</title>

<meta name="description" content="Check 0.9.9: 4. Advanced Features">
<meta name="keywords" content="Check 0.9.9: 4. Advanced Features">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html 1.82">

<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
pre.display {font-family: serif}
pre.format {font-family: serif}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: serif; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: serif; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.roman {font-family:serif; font-weight:normal;}
span.sansserif {font-family:sans-serif; font-weight:normal;}
ul.toc {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">

<a name="Advanced-Features"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tbody><tr><td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_3.html#SRunner-Output" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Convenience-Test-Functions" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_3.html#Tutorial" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/index.html#Top" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_5.html#Conclusion-and-References" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_8.html#Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></tbody></table>
<a name="Advanced-Features-1"></a>
<h1 class="chapter">4. Advanced Features</h1>

<p>What you’ve seen so far is all you need for basic unit testing.  The
features described in this section are additions to Check that make it
easier for the developer to write, run, and analyse tests.
</p>
<table class="menu" border="0" cellspacing="0">
<tbody><tr><td align="left" valign="top"><a href="http://check.sourceforge.net/doc/check_html/check_4.html#Convenience-Test-Functions">4.1 Convenience Test Functions</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">  
</td></tr>
<tr><td align="left" valign="top"><a href="http://check.sourceforge.net/doc/check_html/check_4.html#Running-Multiple-Cases">4.2 Running Multiple Cases</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">      
</td></tr>
<tr><td align="left" valign="top"><a href="http://check.sourceforge.net/doc/check_html/check_4.html#No-Fork-Mode">4.3 No Fork Mode</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">                
</td></tr>
<tr><td align="left" valign="top"><a href="http://check.sourceforge.net/doc/check_html/check_4.html#Test-Fixtures">4.4 Test Fixtures</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">               
</td></tr>
<tr><td align="left" valign="top"><a href="http://check.sourceforge.net/doc/check_html/check_4.html#Multiple-Suites-in-one-SRunner">4.5 Multiple Suites in one SRunner</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">  
</td></tr>
<tr><td align="left" valign="top"><a href="http://check.sourceforge.net/doc/check_html/check_4.html#Selective-Running-of-Tests">4.6 Selective Running of Tests</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="http://check.sourceforge.net/doc/check_html/check_4.html#Testing-Signal-Handling-and-Exit-Values">4.7 Testing Signal Handling and Exit Values</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">  
</td></tr>
<tr><td align="left" valign="top"><a href="http://check.sourceforge.net/doc/check_html/check_4.html#Looping-Tests">4.8 Looping Tests</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">               
</td></tr>
<tr><td align="left" valign="top"><a href="http://check.sourceforge.net/doc/check_html/check_4.html#Test-Timeouts">4.9 Test Timeouts</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">               
</td></tr>
<tr><td align="left" valign="top"><a href="http://check.sourceforge.net/doc/check_html/check_4.html#Determining-Test-Coverage">4.10 Determining Test Coverage</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">   
</td></tr>
<tr><td align="left" valign="top"><a href="http://check.sourceforge.net/doc/check_html/check_4.html#Test-Logging">4.11 Test Logging</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">                
</td></tr>
<tr><td align="left" valign="top"><a href="http://check.sourceforge.net/doc/check_html/check_4.html#Subunit-Support">4.12 Subunit Support</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">             
</td></tr>
</tbody></table>

<hr size="6">
<a name="Convenience-Test-Functions"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tbody><tr><td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Running-Multiple-Cases" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_5.html#Conclusion-and-References" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_8.html#Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></tbody></table>
<a name="Convenience-Test-Functions-1"></a>
<h2 class="section">4.1 Convenience Test Functions</h2>

<p>Using the <code>fail_unless</code> function for all tests can lead to lot of
repetitive code that is hard to read.  For your convenience Check
provides a set of functions (actually macros) for testing often used
conditions.
</p>
<dl compact="compact">
<dt> <code>ck_abort</code>
<a name="index-ck_005fabort"></a>
</dt>
<dd><p>Unconditionally fails test with default message.
</p>
</dd>
<dt> <code>ck_abort_msg</code>
<a name="index-ck_005fabort_005fmsg"></a>
</dt>
<dd><p>Unconditionally fails test with user supplied message.
</p>
</dd>
<dt> <code>ck_assert</code>
<a name="index-ck_005fassert"></a>
</dt>
<dd><p>Fails test if supplied condition evaluates to true. This function is
equivalent to <code>fail_unless</code> with <code>NULL</code> as a message.
</p>
</dd>
<dt> <code>ck_assert_msg</code>
<a name="index-ck_005fassert_005fmsg"></a>
</dt>
<dd><p>Fails test if supplied condition evaluates to true and displays user
provided message. This function is equivalent to <code>fail_unless</code>.
</p>
</dd>
<dt> <code>ck_assert_int_eq</code>
<a name="index-ck_005fassert_005fint_005feq"></a>
</dt>
<dt> <code>ck_assert_int_ne</code>
<a name="index-ck_005fassert_005fint_005fne"></a>
</dt>
<dt> <code>ck_assert_int_lt</code>
<a name="index-ck_005fassert_005fint_005flt"></a>
</dt>
<dt> <code>ck_assert_int_le</code>
<a name="index-ck_005fassert_005fint_005fle"></a>
</dt>
<dt> <code>ck_assert_int_gt</code>
<a name="index-ck_005fassert_005fint_005fgt"></a>
</dt>
<dt> <code>ck_assert_int_ge</code>
<a name="index-ck_005fassert_005fint_005fge"></a>
</dt>
<dd>
<p>Compares two <code>int</code> values and displays predefined message with
condition and values of both input parameters on failure.  The operator
used for comparison is different for each function and is indicated by
the last two letters of the function name.  The abbreviations <code>eq</code>,
<code>ne</code>, <code>lt</code>, <code>le</code>, <code>gt</code>, and <code>ge</code> correspond to
<code>==</code>, <code>!=</code>, <code>&lt;</code>, <code>&lt;=</code>, <code>&gt;</code>, and <code>&gt;=</code>
respectively.
</p>
</dd>
<dt> <code>ck_assert_str_eq</code>
<a name="index-ck_005fassert_005fstr_005feq"></a>
</dt>
<dt> <code>ck_assert_str_ne</code>
<a name="index-ck_005fassert_005fstr_005fne"></a>
</dt>
<dt> <code>ck_assert_str_lt</code>
<a name="index-ck_005fassert_005fstr_005flt"></a>
</dt>
<dt> <code>ck_assert_str_le</code>
<a name="index-ck_005fassert_005fstr_005fle"></a>
</dt>
<dt> <code>ck_assert_str_gt</code>
<a name="index-ck_005fassert_005fstr_005fgt"></a>
</dt>
<dt> <code>ck_assert_str_ge</code>
<a name="index-ck_005fassert_005fstr_005fge"></a>
</dt>
<dd>
<p>Compares two null-terminated <code>char *</code> string values, using the
<code>strcmp()</code> function internally, and displays predefined message
with condition and input parameter values on failure.  The comparison
operator is again indicated by last two letters of the function name.
<code>ck_assert_str_lt(a, b)</code> will pass if the unsigned numerical value
of the character string <code>a</code> is less than that of <code>b</code>.
</p>
</dd>
</dl>

<hr size="6">
<a name="Running-Multiple-Cases"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tbody><tr><td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Convenience-Test-Functions" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#No-Fork-Mode" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_5.html#Conclusion-and-References" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_8.html#Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></tbody></table>
<a name="Running-Multiple-Cases-1"></a>
<h2 class="section">4.2 Running Multiple Cases</h2>

<p>What happens if we pass <code>-1</code> as the <code>amount</code> in
<code>money_create()</code>?  What should happen?  Let’s write a unit test.
Since we are now testing limits, we should also test what happens when
we create <code>Money</code> where <code>amount == 0</code>.  Let’s put these in a
separate test case called “Limits” so that <code>money_suite</code> is
changed like so:
</p>
<table><tbody><tr><td>&nbsp;</td><td><pre class="example"><pre class="verbatim">--- tests/check_money.3.c	2008-12-29 14:48:15.000000000 +0100
+++ tests/check_money.6.c	2008-12-29 14:48:15.000000000 +0100
@@ -14,6 +14,23 @@
 }
 END_TEST
 
+START_TEST (test_money_create_neg)
+{
+  Money *m = money_create (-1, "USD");
+  fail_unless (m == NULL,
+	       "NULL should be returned on attempt to create with "
+	       "a negative amount");
+}
+END_TEST
+
+START_TEST (test_money_create_zero)
+{
+  Money *m = money_create (0, "USD");
+  fail_unless (money_amount (m) == 0, 
+	       "Zero is a valid amount of money");
+}
+END_TEST
+
 Suite *
 money_suite (void)
 {
@@ -24,6 +41,12 @@
   tcase_add_test (tc_core, test_money_create);
   suite_add_tcase (s, tc_core);
 
+  /* Limits test case */
+  TCase *tc_limits = tcase_create ("Limits");
+  tcase_add_test (tc_limits, test_money_create_neg);
+  tcase_add_test (tc_limits, test_money_create_zero);
+  suite_add_tcase (s, tc_limits);
+
   return s;
 }
 
</pre></pre></td></tr></tbody></table>

<p>Now we can rerun our suite, and fix the problem(s). Note that errors
in the “Core” test case will be reported as “Core”, and errors in
the “Limits” test case will be reported as “Limits”, giving you
additional information about where things broke.
</p>
<table><tbody><tr><td>&nbsp;</td><td><pre class="example"><pre class="verbatim">--- src/money.5.c	2008-12-29 14:48:15.000000000 +0100
+++ src/money.6.c	2008-12-29 14:48:15.000000000 +0100
@@ -10,6 +10,11 @@
 Money *
 money_create (int amount, char *currency)
 {
+  if (amount &lt; 0)
+    {
+      return NULL;
+    }
+
   Money *m = malloc (sizeof (Money));
   if (m == NULL)
     {
</pre></pre></td></tr></tbody></table>

<hr size="6">
<a name="No-Fork-Mode"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tbody><tr><td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Running-Multiple-Cases" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Test-Fixtures" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_5.html#Conclusion-and-References" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_8.html#Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></tbody></table>
<a name="No-Fork-Mode-1"></a>
<h2 class="section">4.3 No Fork Mode</h2>

<p>Check normally forks to create a separate address space.  This allows
a signal or early exit to be caught and reported, rather than taking
down the entire test program, and is normally very useful.  However,
when you are trying to debug why the segmentation fault or other
program error occurred, forking makes it difficult to use debugging
tools.  To define fork mode for an <code>SRunner</code> object, you can do
one of the following:
</p>
<a name="index-CK_005fFORK"></a>
<a name="index-srunner_005fset_005ffork_005fstatus_0028_0029"></a>
<ol>
<li>
Define the CK_FORK environment variable to equal “no”.

</li><li>
Explicitly define the fork status through the use of the following
function:

<pre class="verbatim">void srunner_set_fork_status (SRunner * sr, enum fork_status fstat);
</pre></li></ol>

<p>The enum <code>fork_status</code> allows the <code>fstat</code> parameter to
assume the following values: <code>CK_FORK</code> and <code>CK_NOFORK</code>.  An
explicit call to <code>srunner_set_fork_status()</code> overrides the
<code>CK_FORK</code> environment variable.
</p>
<hr size="6">
<a name="Test-Fixtures"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tbody><tr><td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#No-Fork-Mode" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Test-Fixture-Examples" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_5.html#Conclusion-and-References" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_8.html#Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></tbody></table>
<a name="Test-Fixtures-1"></a>
<h2 class="section">4.4 Test Fixtures</h2>

<p>We may want multiple tests that all use the same Money.  In such
cases, rather than setting up and tearing down objects for each unit
test, it may be convenient to add some setup that is constant across
all the tests in a test case.  Each such setup/teardown pair is called
a <em>test fixture</em> in test-driven development jargon.
</p>
<p>A fixture is created by defining a setup and/or a teardown function,
and associating it with a test case.  There are two kinds of test
fixtures in Check: checked and unchecked fixtures. These are defined
as follows:
</p>
<dl compact="compact">
<dt> Checked fixtures</dt>
<dd><p>are run inside the address space created by the fork to create the
unit test.  Before each unit test in a test case, the <code>setup()</code>
function is run, if defined. After each unit test, the
<code>teardown()</code> function is run, if defined.  Since they run inside
the forked address space, if checked fixtures signal or otherwise
fail, they will be caught and reported by the <code>SRunner</code>.  A
checked <code>teardown()</code> fixture will not run if the unit test
fails.
</p>
</dd>
<dt> Unchecked fixtures</dt>
<dd><p>are run in the same address space as the test program. Therefore they
may not signal or exit, but may use the fail functions. The unchecked
<code>setup()</code>, if defined, is run before the test case is
started. The unchecked <code>teardown()</code>, if defined, is run after the
test case is done. An unchecked <code>teardown()</code> fixture will run even
if a unit test fails.
</p></dd>
</dl>

<p>An important  difference is that the checked fixtures are run once per
unit test and the unchecked fixtures are run once per test case.
So for a test case that contains <code>check_one()</code> and
<code>check_two()</code> unit tests,
<code>checked_setup()</code>/<code>checked_teardown()</code> checked fixtures, and
<code>unchecked_setup()</code>/<code>unchecked_teardown()</code> unchecked
fixtures, the control flow would be:
</p><table><tbody><tr><td>&nbsp;</td><td><pre class="verbatim">unchecked_setup();
fork();
checked_setup();
check_one();
checked_teardown();
wait();
fork();
checked_setup();
check_two();
checked_teardown();
wait();
unchecked_teardown();
</pre></td></tr></tbody></table>

<table class="menu" border="0" cellspacing="0">
<tbody><tr><td align="left" valign="top"><a href="http://check.sourceforge.net/doc/check_html/check_4.html#Test-Fixture-Examples">4.4.1 Test Fixture Examples</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">       
</td></tr>
<tr><td align="left" valign="top"><a href="http://check.sourceforge.net/doc/check_html/check_4.html#Checked-vs-Unchecked-Fixtures">4.4.2 Checked vs Unchecked Fixtures</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">  
</td></tr>
</tbody></table>

<hr size="6">
<a name="Test-Fixture-Examples"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tbody><tr><td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Test-Fixtures" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Checked-vs-Unchecked-Fixtures" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Test-Fixtures" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_5.html#Conclusion-and-References" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_8.html#Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></tbody></table>
<a name="Test-Fixture-Examples-1"></a>
<h3 class="subsection">4.4.1 Test Fixture Examples</h3>

<p>We create a test fixture in Check as follows:
</p>
<ol>
<li>
Define global variables, and functions to setup and teardown the
globals.  The functions both take <code>void</code> and return <code>void</code>.
In our example, we’ll make <code>five_dollars</code> be a global created and
freed by <code>setup()</code> and <code>teardown()</code> respectively.

</li><li>
<a name="index-tcase_005fadd_005fchecked_005ffixture_0028_0029"></a>
Add the <code>setup()</code> and <code>teardown()</code> functions to the test
case with <code>tcase_add_checked_fixture()</code>.  In our example, this
belongs in the suite setup function <code>money_suite</code>.

</li><li>
Rewrite tests to use the globals.  We’ll rewrite our first to use
<code>five_dollars</code>.
</li></ol>

<p>Note that the functions used for setup and teardown do not need to be
named <code>setup()</code> and <code>teardown()</code>, but they must take
<code>void</code> and return <code>void</code>.  We’ll update ‘<tt>check_money.c</tt>’
as follows:
</p>
<table><tbody><tr><td>&nbsp;</td><td><pre class="example"><pre class="verbatim">--- tests/check_money.6.c	2008-12-29 14:48:15.000000000 +0100
+++ tests/check_money.7.c	2008-12-29 14:48:15.000000000 +0100
@@ -2,15 +2,26 @@
 #include &lt;check.h&gt;
 #include "../src/money.h"
 
+Money *five_dollars;
+
+void
+setup (void)
+{
+  five_dollars = money_create (5, "USD");
+}
+
+void
+teardown (void)
+{
+  money_free (five_dollars);
+}
+
 START_TEST (test_money_create)
 {
-  Money *m;
-  m = money_create (5, "USD");
-  fail_unless (money_amount (m) == 5, 
+  fail_unless (money_amount (five_dollars) == 5,
 	       "Amount not set correctly on creation");
-  fail_unless (strcmp (money_currency (m), "USD") == 0,
+  fail_unless (strcmp (money_currency (five_dollars), "USD") == 0,
 	       "Currency not set correctly on creation");
-  money_free (m);
 }
 END_TEST
 
@@ -38,6 +49,7 @@
 
   /* Core test case */
   TCase *tc_core = tcase_create ("Core");
+  tcase_add_checked_fixture (tc_core, setup, teardown);
   tcase_add_test (tc_core, test_money_create);
   suite_add_tcase (s, tc_core);
 
</pre></pre></td></tr></tbody></table>

<hr size="6">
<a name="Checked-vs-Unchecked-Fixtures"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tbody><tr><td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Test-Fixture-Examples" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Multiple-Suites-in-one-SRunner" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Test-Fixtures" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_5.html#Conclusion-and-References" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_8.html#Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></tbody></table>
<a name="Checked-vs-Unchecked-Fixtures-1"></a>
<h3 class="subsection">4.4.2 Checked vs Unchecked Fixtures</h3>

<p>Checked fixtures run once for each unit test in a test case, and so
they should not be used for expensive setup.  However, if a checked
fixture fails and <code>CK_FORK</code> mode is being used, it will not bring
down the entire framework.
</p>
<p>On the other hand, unchecked fixtures run once for an entire test
case, as opposed to once per unit test, and so can be used for
expensive setup.  However, since they may take down the entire test
program, they should only be used if they are known to be safe.
</p>
<p>Additionally, the isolation of objects created by unchecked fixtures
is not guaranteed by <code>CK_NOFORK</code> mode.  Normally, in
<code>CK_FORK</code> mode, unit tests may abuse the objects created in an
unchecked fixture with impunity, without affecting other unit tests in
the same test case, because the fork creates a separate address space.
However, in <code>CK_NOFORK</code> mode, all tests live in the same address
space, and side effects in one test will affect the unchecked fixture
for the other tests.
</p>
<p>A checked fixture will generally not be affected by unit test side
effects, since the <code>setup()</code> is run before each unit test.  There
is an exception for side effects to the total environment in which the
test program lives: for example, if the <code>setup()</code> function
initializes a file that a unit test then changes, the combination of
the <code>teardown()</code> function and <code>setup()</code> fuction must be able
to restore the environment for the next unit test.
</p>
<p>If the <code>setup()</code> function in a fixture fails, in either checked
or unchecked fixtures, the unit tests for the test case, and the
<code>teardown()</code> function for the fixture will not be run.  A fixture
error will be created and reported to the <code>SRunner</code>.
</p>
<hr size="6">
<a name="Multiple-Suites-in-one-SRunner"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tbody><tr><td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Checked-vs-Unchecked-Fixtures" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Selective-Running-of-Tests" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_5.html#Conclusion-and-References" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_8.html#Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></tbody></table>
<a name="Multiple-Suites-in-one-SRunner-1"></a>
<h2 class="section">4.5 Multiple Suites in one SRunner</h2>

<p>In a large program, it will be convenient to create multiple suites,
each testing a module of the program.  While one can create several
test programs, each running one <code>Suite</code>, it may be convenient to
create one main test program, and use it to run multiple suites.  The
Check test suite provides an example of how to do this. The main
testing program is called <code>check_check</code>, and has a header file
that declares suite creation functions for all the module tests:
</p><table><tbody><tr><td>&nbsp;</td><td><pre class="verbatim">Suite *make_sub_suite (void);
Suite *make_sub2_suite (void);
Suite *make_master_suite (void);
Suite *make_list_suite (void);
Suite *make_msg_suite (void);
Suite *make_log_suite (void);
Suite *make_limit_suite (void);
Suite *make_fork_suite (void);
Suite *make_fixture_suite (void);
Suite *make_pack_suite (void);
</pre></td></tr></tbody></table>

<a name="index-srunner_005fadd_005fsuite_0028_0029"></a>
<p>The function <code>srunner_add_suite()</code> is used to add additional
suites to an <code>SRunner</code>.  Here is the code that sets up and runs
the <code>SRunner</code> in the <code>main()</code> function in
‘<tt>check_check_main.c</tt>’:
</p><table><tbody><tr><td>&nbsp;</td><td><pre class="verbatim">SRunner *sr;
sr = srunner_create (make_master_suite ());
srunner_add_suite (sr, make_list_suite ());
srunner_add_suite (sr, make_msg_suite ());
srunner_add_suite (sr, make_log_suite ());
srunner_add_suite (sr, make_limit_suite ());
srunner_add_suite (sr, make_fork_suite ());
srunner_add_suite (sr, make_fixture_suite ());
srunner_add_suite (sr, make_pack_suite ());
</pre></td></tr></tbody></table>

<hr size="6">
<a name="Selective-Running-of-Tests"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tbody><tr><td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Multiple-Suites-in-one-SRunner" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Testing-Signal-Handling-and-Exit-Values" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_5.html#Conclusion-and-References" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_8.html#Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></tbody></table>
<a name="Selective-Running-of-Tests-1"></a>
<h2 class="section">4.6 Selective Running of Tests</h2>

<a name="index-CK_005fRUN_005fSUITE"></a>
<a name="index-CK_005fRUN_005fCASE"></a>
<p>After adding a couple of suites and some test cases in each, it is
sometimes practical to be able to run only one suite, or one
specific test case, without recompiling the test code. There are
two environment variables available that offers this ability,
<code>CK_RUN_SUITE</code> and <code>CK_RUN_CASE</code>. Just set the value to
the name of the suite and/or test case you want to run. These
environment variables can also be a good integration tool for
running specific tests from within another tool, e.g. an IDE.
</p>  
<hr size="6">
<a name="Testing-Signal-Handling-and-Exit-Values"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tbody><tr><td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Selective-Running-of-Tests" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Looping-Tests" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_5.html#Conclusion-and-References" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_8.html#Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></tbody></table>
<a name="Testing-Signal-Handling-and-Exit-Values-1"></a>
<h2 class="section">4.7 Testing Signal Handling and Exit Values</h2>

<a name="index-tcase_005fadd_005ftest_005fraise_005fsignal_0028_0029"></a>

<p>To enable testing of signal handling, there is a function
<code>tcase_add_test_raise_signal()</code> which is used instead of
<code>tcase_add_test()</code>.  This function takes an additional signal
argument, specifying a signal that the test expects to receive.  If no
signal is received this is logged as a failure.  If a different signal
is received this is logged as an error.
</p>
<p>The signal handling functionality only works in CK_FORK mode.
</p>
<a name="index-tcase_005fadd_005fexit_005ftest_0028_0029"></a>

<p>To enable testing of expected exits, there is a function
<code>tcase_add_exit_test()</code> which is used instead of <code>tcase_add_test()</code>.
This function takes an additional expected exit value argument,
specifying a value that the test is expected to exit with.  If the test
exits with any other value this is logged as a failure.  If the test exits
early this is logged as an error.
</p>
<p>The exit handling functionality only works in CK_FORK mode.
</p>
<hr size="6">
<a name="Looping-Tests"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tbody><tr><td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Testing-Signal-Handling-and-Exit-Values" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Test-Timeouts" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_5.html#Conclusion-and-References" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_8.html#Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></tbody></table>
<a name="Looping-Tests-1"></a>
<h2 class="section">4.8 Looping Tests</h2>

<p>Looping tests are tests that are called with a new context for each
loop iteration.  This makes them ideal for table based tests.  If
loops are used inside ordinary tests to test multiple values, only the
first error will be shown before the test exits.  However, looping
tests allow for all errors to be shown at once, which can help out
with debugging.
</p>
<a name="index-tcase_005fadd_005floop_005ftest_0028_0029"></a>
<p>Adding a normal test with <code>tcase_add_loop_test()</code> instead of
<code>tcase_add_test()</code> will make the test function the body of a
<code>for</code> loop, with the addition of a fork before each call.  The
loop variable <code>_i</code> is available for use inside the test function;
for example, it could serve as an index into a table.  For failures,
the iteration which caused the failure is available in error messages
and logs.  
</p>
<p>Start and end values for the loop are supplied when adding the test.
The values are used as in a normal <code>for</code> loop.  Below is some
pseudo-code to show the concept:
</p><table><tbody><tr><td>&nbsp;</td><td><pre class="verbatim">for (_i = tfun-&gt;loop_start; _i &lt; tfun-&gt;loop_end; _i++)
{
  fork();      /* New context */
  tfun-&gt;f(_i);  /* Call test function */
  wait();      /* Wait for child to terminate */
}
</pre></td></tr></tbody></table>

<p>An example of looping test usage follows:
</p><table><tbody><tr><td>&nbsp;</td><td><pre class="verbatim">static const int primes[5] = {2,3,5,7,11};

START_TEST (check_is_prime)
{
  fail_unless (is_prime (primes[_i]));
}
END_TEST

...

tcase_add_loop_test (tcase, check_is_prime, 0, 5);
</pre></td></tr></tbody></table>

<p>Looping tests work in <code>CK_NOFORK</code> mode as well, but without the
forking.  This means that only the first error will be shown.
</p>
<hr size="6">
<a name="Test-Timeouts"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tbody><tr><td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Looping-Tests" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Determining-Test-Coverage" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_5.html#Conclusion-and-References" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_8.html#Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></tbody></table>
<a name="Test-Timeouts-1"></a>
<h2 class="section">4.9 Test Timeouts</h2>

<a name="index-tcase_005fset_005ftimeout_0028_0029"></a>
<a name="index-CK_005fDEFAULT_005fTIMEOUT"></a>
<a name="index-CK_005fTIMEOUT_005fMULTIPLIER"></a>
<p>To be certain that a test won’t hang indefinitely, all tests are run
with a timeout, the default being 4 seconds.  If the test is not
finished within that time, it is killed and logged as an error.
</p>
<p>The timeout for a specific test case, which may contain multiple unit
tests, can be changed with the <code>tcase_set_timeout()</code> function.
The default timeout used for all test cases can be changed with the
environment variable <code>CK_DEFAULT_TIMEOUT</code>, but this will not
override an explicitly set timeout.  Another way to change the timeout
length is to use the <code>CK_TIMEOUT_MULTIPLIER</code> environment variable,
which multiplies all timeouts, including those set with
<code>tcase_set_timeout()</code>, with the supplied integer value. All timeout
arguments are in seconds and a timeout of 0 seconds turns off the timeout
functionality.
</p>
<p>Test timeouts are only available in CK_FORK mode.
</p>
<hr size="6">
<a name="Determining-Test-Coverage"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tbody><tr><td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Test-Timeouts" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Test-Logging" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_5.html#Conclusion-and-References" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_8.html#Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></tbody></table>
<a name="Determining-Test-Coverage-1"></a>
<h2 class="section">4.10 Determining Test Coverage</h2>

<p>The term <em>code coverage</em> refers to the extent that the statements
of a program are executed during a run.  Thus, <em>test coverage</em>
refers to code coverage when executing unit tests.  This information
can help you to do two things:
</p>
<ul>
<li> 
Write better tests that more fully exercise your code, thereby
improving confidence in it.

</li><li>
Detect dead code that could be factored away.
</li></ul>
  
<p>Check itself does not provide any means to determine this test
coverage; rather, this is the job of the compiler and its related
tools.  In the case of <code>gcc</code> this information is easy to
obtain, and other compilers should provide similar facilities.
</p>
<p>Using <code>gcc</code>, first enable test coverage profiling when
building your source by specifying the ‘<samp>-fprofile-arcs</samp>’ and
‘<samp>-ftest-coverage</samp>’ switches:
</p><table><tbody><tr><td>&nbsp;</td><td><pre class="verbatim">$ gcc -g -Wall -fprofile-arcs -ftest-coverage -o foo foo.c foo_check.c
</pre></td></tr></tbody></table>

<p>You will see that an additional ‘<tt>.gcno</tt>’ file is created for each
‘<tt>.c</tt>’ input file.  After running your tests the normal way, a
‘<tt>.gcda</tt>’ file is created for each ‘<tt>.gcno</tt>’ file.  These
contain the coverage data in a raw format.  To combine this
information and a source file into a more readable format you can use
the <code>gcov</code> utility:
</p><table><tbody><tr><td>&nbsp;</td><td><pre class="verbatim">$ gcov foo.c
</pre></td></tr></tbody></table>

<p>This will produce the file ‘<tt>foo.c.gcov</tt>’ which looks like this:
</p><table><tbody><tr><td>&nbsp;</td><td><pre class="verbatim">     -:   41:     * object */
    18:   42:    if (ht-&gt;table[p] != NULL) {
     -:   43:        /* replaces the current entry */
 #####:   44:        ht-&gt;count--;
 #####:   45:        ht-&gt;size -= ht-&gt;table[p]-&gt;size +
 #####:   46:          sizeof(struct hashtable_entry);   
</pre></td></tr></tbody></table>

<p>As you can see this is an annotated source file with three columns:
usage information, line numbers, and the original source.  The usage
information in the first column can either be ’-’, which means that
this line does not contain code that could be executed; ’#####’, which
means this line was never executed although it does contain
code—these are the lines that are probably most interesting for you;
or a number, which indicates how often that line was executed.
</p>
<p>This is of course only a very brief overview, but it should illustrate
how determining test coverage generally works, and how it can help
you.  For more information or help with other compilers, please refer
to the relevant manuals.
</p>
<hr size="6">
<a name="Test-Logging"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tbody><tr><td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Determining-Test-Coverage" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#XML-Logging" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_5.html#Conclusion-and-References" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_8.html#Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></tbody></table>
<a name="Test-Logging-1"></a>
<h2 class="section">4.11 Test Logging</h2>

<a name="index-srunner_005fset_005flog_0028_0029"></a>
<p>Check supports an operation to log the results of a test run.  To use
test logging, call the <code>srunner_set_log()</code> function with the name
of the log file you wish to create:
</p><table><tbody><tr><td>&nbsp;</td><td><pre class="verbatim">SRunner *sr;
sr = srunner_create (make_s1_suite ());
srunner_add_suite (sr, make_s2_suite ());
srunner_set_log (sr, "test.log");
srunner_run_all (sr, CK_NORMAL);
</pre></td></tr></tbody></table>

<p>In this example, Check will write the results of the run to
‘<tt>test.log</tt>’.  The <code>print_mode</code> argument to
<code>srunner_run_all()</code> is ignored during test logging; the log will
contain a result entry, organized by suite, for every test run.  Here
is an example of test log output:
</p><table><tbody><tr><td>&nbsp;</td><td><pre class="verbatim">Running suite S1 
ex_log_output.c:8:P:Core:test_pass: Test passed
ex_log_output.c:14:F:Core:test_fail: Failure
ex_log_output.c:18:E:Core:test_exit: (after this point) Early exit
with return value 1
Running suite S2 
ex_log_output.c:26:P:Core:test_pass2: Test passed
Results for all suites run:
50%: Checks: 4, Failures: 1, Errors: 1
</pre></td></tr></tbody></table>

<p>Another way to enable test logging is to use the <code>CK_LOG_FILE_NAME</code>
environment variable. When set tests will be logged to the specified file name.
If log file is specified with both <code>CK_LOG_FILE_NAME</code> and
<code>srunner_set_log()</code>, the name provided to <code>srunner_set_log()</code> will
be used.
</p>

<table class="menu" border="0" cellspacing="0">
<tbody><tr><td align="left" valign="top"><a href="http://check.sourceforge.net/doc/check_html/check_4.html#XML-Logging">4.11.1 XML Logging</a></td><td>&nbsp;&nbsp;</td><td align="left" valign="top">                 
</td></tr>
</tbody></table>

<hr size="6">
<a name="XML-Logging"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tbody><tr><td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Test-Logging" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Subunit-Support" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#Test-Logging" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_5.html#Conclusion-and-References" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_8.html#Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></tbody></table>
<a name="XML-Logging-1"></a>
<h3 class="subsection">4.11.1 XML Logging</h3>

<a name="index-srunner_005fset_005fxml_0028_0029"></a>
<a name="index-srunner_005fhas_005fxml_0028_0029"></a>
<a name="index-srunner_005fxml_005ffname_0028_0029"></a>
<p>The log can also be written in XML.  The following functions define
the interface for XML logs:
</p><table><tbody><tr><td>&nbsp;</td><td><pre class="verbatim">void srunner_set_xml (SRunner *sr, const char *fname);
int srunner_has_xml (SRunner *sr);
const char *srunner_xml_fname (SRunner *sr);
</pre></td></tr></tbody></table>

<p>XML output is enabled by a call to <code>srunner_set_xml()</code> before the tests
are run. Here is an example of an XML log:
</p><table><tbody><tr><td>&nbsp;</td><td><pre class="verbatim">&lt;?xml version="1.0"?&gt;
&lt;?xml-stylesheet type="text/xsl" href="http://check.sourceforge.net/xml/check_unittest.xslt"?&gt;
&lt;testsuites xmlns="http://check.sourceforge.net/ns"&gt;
  &lt;datetime&gt;2012-10-19 09:56:06&lt;/datetime&gt;
  &lt;suite&gt;
    &lt;title&gt;S1&lt;/title&gt;
    &lt;test result="success"&gt;
      &lt;path&gt;.&lt;/path&gt;
      &lt;fn&gt;ex_xml_output.c:10&lt;/fn&gt;
      &lt;id&gt;test_pass&lt;/id&gt;
      &lt;iteration&gt;0&lt;/iteration&gt;
      &lt;duration&gt;0.000013&lt;/duration&gt;
      &lt;description&gt;Core&lt;/description&gt;
      &lt;message&gt;Passed&lt;/message&gt;
    &lt;/test&gt;
    &lt;test result="failure"&gt;
      &lt;path&gt;.&lt;/path&gt;
      &lt;fn&gt;ex_xml_output.c:16&lt;/fn&gt;
      &lt;id&gt;test_fail&lt;/id&gt;
      &lt;iteration&gt;0&lt;/iteration&gt;
      &lt;duration&gt;-1.000000&lt;/duration&gt;
      &lt;description&gt;Core&lt;/description&gt;
      &lt;message&gt;Failure&lt;/message&gt;
    &lt;/test&gt;
    &lt;test result="error"&gt;
      &lt;path&gt;.&lt;/path&gt;
      &lt;fn&gt;ex_xml_output.c:20&lt;/fn&gt;
      &lt;id&gt;test_exit&lt;/id&gt;
      &lt;iteration&gt;0&lt;/iteration&gt;
      &lt;duration&gt;-1.000000&lt;/duration&gt;
      &lt;description&gt;Core&lt;/description&gt;
      &lt;message&gt;Early exit with return value 1&lt;/message&gt;
    &lt;/test&gt;
  &lt;/suite&gt;
  &lt;suite&gt;
    &lt;title&gt;S2&lt;/title&gt;
    &lt;test result="success"&gt;
      &lt;path&gt;.&lt;/path&gt;
      &lt;fn&gt;ex_xml_output.c:28&lt;/fn&gt;
      &lt;id&gt;test_pass2&lt;/id&gt;
      &lt;iteration&gt;0&lt;/iteration&gt;
      &lt;duration&gt;0.000011&lt;/duration&gt;
      &lt;description&gt;Core&lt;/description&gt;
      &lt;message&gt;Passed&lt;/message&gt;
    &lt;/test&gt;
    &lt;test result="failure"&gt;
      &lt;path&gt;.&lt;/path&gt;
      &lt;fn&gt;ex_xml_output.c:34&lt;/fn&gt;
      &lt;id&gt;test_loop&lt;/id&gt;
      &lt;iteration&gt;0&lt;/iteration&gt;
      &lt;duration&gt;-1.000000&lt;/duration&gt;
      &lt;description&gt;Core&lt;/description&gt;
      &lt;message&gt;Iteration 0 failed&lt;/message&gt;
    &lt;/test&gt;
    &lt;test result="success"&gt;
      &lt;path&gt;.&lt;/path&gt;
      &lt;fn&gt;ex_xml_output.c:34&lt;/fn&gt;
      &lt;id&gt;test_loop&lt;/id&gt;
      &lt;iteration&gt;1&lt;/iteration&gt;
      &lt;duration&gt;0.000010&lt;/duration&gt;
      &lt;description&gt;Core&lt;/description&gt;
      &lt;message&gt;Passed&lt;/message&gt;
    &lt;/test&gt;
    &lt;test result="failure"&gt;
      &lt;path&gt;.&lt;/path&gt;
      &lt;fn&gt;ex_xml_output.c:34&lt;/fn&gt;
      &lt;id&gt;test_loop&lt;/id&gt;
      &lt;iteration&gt;2&lt;/iteration&gt;
      &lt;duration&gt;-1.000000&lt;/duration&gt;
      &lt;description&gt;Core&lt;/description&gt;
      &lt;message&gt;Iteration 2 failed&lt;/message&gt;
    &lt;/test&gt;
  &lt;/suite&gt;
  &lt;suite&gt;
    &lt;title&gt;XML escape &amp;quot; &amp;apos; &amp;lt; &amp;gt; &amp;amp; tests&lt;/title&gt;
    &lt;test result="failure"&gt;
      &lt;path&gt;.&lt;/path&gt;
      &lt;fn&gt;ex_xml_output.c:40&lt;/fn&gt;
      &lt;id&gt;test_xml_esc_fail_msg&lt;/id&gt;
      &lt;iteration&gt;0&lt;/iteration&gt;
      &lt;duration&gt;-1.000000&lt;/duration&gt;
      &lt;description&gt;description &amp;quot; &amp;apos; &amp;lt; &amp;gt; &amp;amp;&lt;/description&gt;
      &lt;message&gt;fail &amp;quot; &amp;apos; &amp;lt; &amp;gt; &amp;amp; message&lt;/message&gt;
    &lt;/test&gt;
  &lt;/suite&gt;
  &lt;duration&gt;0.001610&lt;/duration&gt;
&lt;/testsuites&gt;
</pre></td></tr></tbody></table>

<p>XML logging can be enabled by an environment variable as well. If
<code>CK_XML_LOG_FILE_NAME</code> environment variable is set, the XML test log will
be written to specified file name. If XML log file is specified with both
<code>CK_XML_LOG_FILE_NAME</code> and <code>srunner_set_xml()</code>, the name provided
to <code>srunner_set_xml()</code> will be used.
</p>
<p>If both plain text and XML log files are specified, by any of above methods,
then check will log to both files. In other words logging in plain text and XML
format simultaneously is supported.
</p>
<hr size="6">
<a name="Subunit-Support"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tbody><tr><td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_4.html#XML-Logging" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_5.html#Conclusion-and-References" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_5.html#Conclusion-and-References" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_8.html#Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></tbody></table>
<a name="Subunit-Support-1"></a>
<h2 class="section">4.12 Subunit Support</h2>

<p>Check supports running test suites with subunit output. This can be useful to
combine test results from multiple languages, or to perform programmatic
analysis on the results of multiple check test suites or otherise handle test
results in a programmatic manner. Using subunit with check is very straight
forward. There are two steps:
1) In your check test suite driver pass ’CK_SUBUNIT’ as the output mode
for your srunner.
</p><table><tbody><tr><td>&nbsp;</td><td><pre class="verbatim">SRunner *sr;
sr = srunner_create (make_s1_suite ());
srunner_add_suite (sr, make_s2_suite ());
srunner_run_all (sr, CK_SUBUNIT);
</pre></td></tr></tbody></table>
<p>2) Setup your main language test runner to run your check based test
executable. For instance using python:
</p><table><tbody><tr><td>&nbsp;</td><td><pre class="verbatim">import subunit

class ShellTests(subunit.ExecTestCase):
    """Run some tests from the C codebase."""

    def test_group_one(self):
        """./foo/check_driver"""

    def test_group_two(self):
        """./foo/other_driver"""
</pre></td></tr></tbody></table>

<p>In this example, running the test suite ShellTests in python (using any test
runner - unittest.py, tribunal, trial, nose or others) will run
./foo/check_driver and ./foo/other_driver and report on their result.
</p>
<p>Subunit is hosted on launchpad - the <a href="https://launchpad.net/subunit/">subunit</a> project there contains bug tracker, future plans, and source code
control details.
</p>
<hr size="6">
<table cellpadding="1" cellspacing="1" border="0">
<tbody><tr><td valign="middle" align="left">[<a href="./Check 0.9.9  4. Advanced Features_files/Check 0.9.9  4. Advanced Features.html" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_5.html#Conclusion-and-References" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/index.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_8.html#Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="http://check.sourceforge.net/doc/check_html/check_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></tbody></table>
<p>
 <font size="-1">
  This document was generated by <em>Fredrik Hugosson</em> on <em>November 12, 2012</em> using <a href="http://www.nongnu.org/texi2html/"><em>texi2html 1.82</em></a>.
 </font>
 <br>

</p>


</body></html>